Partner OVD Integration API

The following document highlights the details of the Partner OVD Integration API.

API Description

Objective

The Partner OVD Integration API accepts the front and back side images of an officially valid document (OVD) as the input and performs the following actions:

1. Optical character recognition on the image with the front side of the document.
2. Optical character recognition on the image with the back side of the document.
3. A government database check based on the document type.
4. A name match between the name extracted from the OCR and the name extracted from the government database.

Input	Output
The images of both the sides of an officially valid document and its type	OCR results for front and back sides, government database check results, and name match verification

API URL

https://ind-engine.thomas.hyperverge.co/v1/ovd_verification

API Endpoint

ovd_verification

Overview

The Partner OVD Integration API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format, and you should upload all images and files as form-data through a POST request.

Method - POST

Authentication

You need a unique pair of application ID ( appId ) and application key ( appKey ) from HyperVerge to verify your identity for accessing the Partner OVD Integration API.

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload	multipart/form-data
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Mandatory	Unique ID for the customer journey	Any defined unique value mapped to a transaction in your business ecosystem

Inputs

The following table provides the details of the parameters required for the Partner OVD Integration API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
front	Mandatory	file	The image of the document capturing the frontside of OVD	Image file (JPEG, JPG, or PNG)	Not Applicable
back	Mandatory	file	The image of the document capturing the backside of OVD	Image file (JPEG, JPG, or PNG)	Not Applicable
documentId	Mandatory	string	The type of the officially valid document. It accepts any one of the following values: Value Description id Aadhaar voterid VoterId passport Passport dl Driving License	id, voterid, passport, dl	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the Partner OVD Integration API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/ovd_verification' \
--header 'appid: <Enter_the_appId-Shared-by-HyperVerge>' \
--header 'appkey: <Enter_the_appKey-shared-by-HyperVerge>' \
--header 'transactionId : <Enter_the_Transaction_ID>' \
--form 'documentId="dl"' \
--form 'front=@""' \
--form 'back=@""'

Success Response

The following code snippet demonstrates a success response from the Partner OVD Integration API:

{
 "statusCode": 200,
 "metaData": {
   "requestId": "",
   "transactionId": ""
 },
 "application_status": "auto_approved",
 "result": {
   "details": {
     "front": <Front OCR response>,
     "back": <Back OCR response>,
     "dbCheck": <DB Check response>,
     "nameMatch": <Name match response>
   }
 }
}

Success Response Details

The following table outlines the details of the success response from the Partner OVD Integration API:

Parameter	Type	Description
statusCode	integer	The HTTP status code for the response
metaData	object	The JSON object containing request and transaction identifiers
application_status	string	The status of the application processing
result	object	The JSON object containing the verification details
front	object	It reflects the fields extracted by the OCR for the front side of the document
back	object	It reflects the fields extracted by the OCR for the back side of the document
dbCheck	object	If the Partner OVD Integration API finds a matching document in the government database, it extracts and returns all the details from the database. Otherwise, it returns a failure status. info This field is not applicable when the OVD input is an Aadhaar. This works only for, Driving License - when the date of birth and the driving license number is extracted succcessfully by the OCR. Voter ID - when the voter ID number is extracted succcessfully by the OCR.
nameMatch	object	This object in the response contains the value 'true' when the name extracted from the input document in the request matches the one extracted from the government database. info If the dbCheck returns a failure, this name match action is not executed.

Failure Response

The following code snippet demonstrates a failure response from the Partner OVD Integration API:

{
    "status": "failure",
    "statusCode": 400,
    "message": "Input Validation Error: requires property \"back\""
}

Error Responses

The following are some error responses from the Partner OVD Integration API:

Missing Image Input - back

{
    "message": "Input Validation Error: requires property \"back\"",
    "statusCode": 400,
    "status": "failure"
}

Missing/Invalid Credentials

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

Rate Limit Exceeded

{
    "status": "failure",
    "statusCode": 429,
    "error": "Rate limit exceeded"
}

Internal Server Error

{
    "statusCode": 500,
    "status": "failure",
    "error": "Internal Server Error"
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	Input Validation Error: requires property "back"	The request is missing an input for the back parameter	Ensure the request includes the back parameter with a valid image file
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values	Verify and provide valid appId and appKey credentials
429	Rate limit exceeded	This error is returned when the number of transactions per minute has crossed the limit set for your credentials	Retry the request after some time or contact the HyperVerge team if the issue persists
500	Internal Server Error	Kindly check the request headers or contact the HyperVerge team for resolution.	Check the request headers or contact the HyperVerge team for resolution